<html>
	<head>
		<meta name="vs_targetSchema" content="http://schemas.microsoft.com/intellisense/ie5">
		<meta http-equiv="Content-Language" content="en">
		<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
		<link rel="stylesheet" href="resources/style.css">
		<title>Configuration Editor Help</title>
	</head>
	<body>
		<p>
			<img border="0" src="resources/LogoOpenMI.jpg" width="83" height="73"><img border="0" src="resources/OpenMI-titleonly.jpg" width="190" height="41"></p>
		<hr>
		<h1>Configuration Editor Help</h1>
		<h2>Introduction</h2>
		<p class="stdtext">
			OpenMI standard provides capability for linking of different computational
			models mostly used for water and environment modeling. After this standard was
			introduced, the need of user friendly application able to link OpenMI compliant
			models arised. <b>Oatc.OpenMI.ConfigurationEditor.exe</b> is such an application</p>
		<p class="stdtext">
			If you are new to OpenMI, please take a look at <b>Links</b> section
			of this document to find sources of information about OpenMI.
		</p>
		<h2>Working with Configuration Editor</h2>
		<h3>Adding models to composition</h3>
		<p class="stdtext">
			As the first step you have to add models into your composition. In menu click
			on <b>Composition&nbsp;&gt;&nbsp;Add&nbsp;Model</b>, in open-file dialog choose
			OMI file of the model and click <b>OK</b>. Rectangle describing your model
			should now appear in composition area. Same operation can be performed in popup
			menu, which you can open by clicking of right mouse button.
			<br>
			<img class="pict" src="resources/add_model.png"><img class="pict" src="resources/model_added.png">
			<br>
			Repeat this procedure for each model which you want to have in your
			composition. There's only one limitation: two models cannot have same ModelID.
			<br>
			<br>
			If you want to show properties of the model, click on <b>Composition&nbsp;&gt;&nbsp;Model&nbsp;properties...</b>
			and select requested model. Same operation can also be performed in popup menu
			by right-clicking of model rectangle and selecting <b>Model&nbsp;properties...</b>.
			<br>
			<img class="pict" src="resources/model_properties.png">
			<br>
			See section <b>Linking of models</b> for more detail about the
			exchange items tree.
		</p>
		<p class="stdtext">
			You should also add Trigger as well, if you want to run simulation of the
			composition. In menu click <b>Composition&nbsp;&gt;&nbsp;Add&nbsp;Trigger</b>.
			Trigger is special model used to fire simulation, see section <b>Running
				simulation</b> for more detail.
		</p>
		<a name="#Linking"></a>
		<h3>Linking of models</h3>
		<p class="stdtext">
			If you want to make first link between two different models in some direction,
			you must create connection between them first. Connection is an abstraction
			that collects links between two models, all its links have same direction as
			connection itself. In menu click <b>Composition&nbsp;&gt;&nbsp;Add&nbsp;Connection</b>
			or in popup menu click <b>Add&nbsp;Connection</b>, click on the source model's
			rectangle and afterwards click on target model's rectangle. Source model is
			model providing data, target model is model accepting data. Line connecting two
			models with small triangle in the middle should now appear in the composition
			area.
			<br>
			<img class="pict" src="resources/add_connection.png"><img class="pict" src="resources/connection_added.png">
			<br>
			Now you can add links to connection. Click on small triangle on the connection
			to show <b>Connection properties</b> dialog. Here you can see two trees
			describing exchange items of two connected models, <b>Output exchange items</b>
			are from source model, <b>Input exchange items</b> from target model.
			First-level nodes of this trees correspond to quantities, second-level nodes to
			element sets. In case of <b>Output exchange items</b> there are third-level
			nodes which show all available <b>Data operations</b> for output exchange item.
			<br>
			<br>
			If you click on quantity, element set or data operation, it's properties
			appears on the grid right. These properties are all read-only, only data
			operations can have writeable arguments.
			<br>
			<br>
			OpenMI link generally consists of one output quantity, output element set,
			input quantity and input element set. In the bottom of the window you can see
			list of such links in this connection and one item named <b>&lt;New...&gt;</b>.
			If you want to add new link, click on this item, check output quantity, element
			set and maybe some data operations, check input quantity and element set and
			aftewards click <b>Apply</b> button. New link now appears in the list. If you
			want to edit existing link, click on it in the list, change it's properties and
			click <b>Apply</b>. To remove existing link, click <b>Remove</b> button.
			<br>
			<img class="pict" src="resources/connection_properties.png">
			<br>
			If you use <b>Use Dimension filter</b> option, there will be shown only input
			exchange items with same dimension as the quantity checked in output exchange
			items. Similar behaviour has <b>Use ElementType filter</b>, the only difference
			is that there are shown input exchange items which have either ID-based element
			set or element set of same type (i.e. line, polygon, poly-line, ...) and with
			same number of elements like checked output element set.
			<br>
			<br>
			<b>ElementSet viewer</b> is simple tool used to show spatial properties of one
			or two ElementSets. Check output and/or input ElementSet and click
			corresponding button.
			<br>
			<img class="pict" src="resources/elementset_viewer.png">
			<br>
		</p>
		<a name="#Running"></a>
		<h3>Running simulation</h3>
		<p class="stdtext">
			Before you can run simulation, make sure the <b>Trigger</b> is part of your
			composition and is linked to one model. Trigger is special model used to fire
			simulation, it just once invokes <b>GetValues()</b> on linked model at
			specified time.
			<br>
			<br>
			In menu click <b>Composition&nbsp;&gt;&nbsp;Run...</b> to show <b>Run properties</b>
			dialog.
			<br>
			<img class="pict" src="resources/run_properties.png">
			<br>
			Here you can set what types of event do you want to listen during computation,
			these events can be stored into log file (check <b>Log to file</b> and type or
			browse filename of log-file) and/or shown in list-box (check <b>Show events in
				listbox</b>). Remember that handling of events can cause large performance
			overheads for models performing fast timesteps, especially showing events in
			list-box is relatively slow.
			<br>
			<br>
			<b>Invoke trigger at</b> defines the time, when trigger invokes <b>GetValues()</b>
			on linked model. It can be automatically set to latest overlapping time of all
			models by clicking <b>Lastest overlapping</b> button. See <a href="#Remarks">Remarks</a>
			section about what format of date and time to use.
			<br>
			<br>
			<b>Don't use separate thread</b> check-box determines whether simulation is run
			in same thread as user interface (UI). If simulation runs in separate thread,
			UI responds immediately and user can even stop it. However, some components
			wrapping for example model using <i>COM single-thread apartments</i> can run in
			problems, because model (in this case <i>COM</i> object) is intialized in UI
			thread and not in simulation thread. If simulation runs in same thread as user
			interface, and timestep of some model takes long time to execute, UI can stop
			responding and user isn't able to stop simulation as well. See
			<a href="#command_line">Command-line options</a> to see how you can change default
			thread apartment state.
			<br>
			<br>
			To start the simulation, click <b>RUN !!!</b>.
			<br>
			<img class="pict" src="resources/run.png">
			<br>
			After simulation finished, message-box asking you whether you want to reload
			the project appears. OpenMI standard doesn't include functionallity to
			reinitialize models after simulation finished, and model may not be able to run
			simulation again and/or have malformed properties (like exchange items, model
			ID, etc...) Reloading is just workaround to this behaviour, it's same operation
			like if you save the project, restart Configuration Editor and open your project again.
			However, some models can delete result files of their simulation if you reload
			them.
			<br>
			<img class="pict" src="resources/reload_question.png">
			<br>
			If you decide not to reload the composition, you can do it later in menu <b>File&nbsp;&gt;&nbsp;Reload</b>.
		</p>
		<a name="#Remarks"></a>
		<h3>Appendix</h3>
		<h4>Globalization</h4>
		<p class="stdtext">
			Whole application uses english/US culture for converting (string to DateTime,
			DateTime to string, string to int, etc...). For example <b>Trigger invoke at</b>
			in <b>Run properties</b> dialog uses <i>MM/dd/yyyy hh:mm:ss AM|PM</i> format.
		</p>

		<a name="#command_line"></a>
		<h4>Advanced options</h4>
		<p class="stdtext">
			In menu <b>Options&nbsp;&gt;&nbsp;Register file extensions</b> you can register
			<b>OPR</b> and <b>OMI</b> file extension to be opened with this Configuration Editor application, e.g.
			from Explorer. In such case or if you open <b>OPR</b> file, Configuration Editor application starts and opens this file,
			if you open <b>OMI</b> file, Configuration Editor creates a new composition with just one model from this file. This registartion
			can also be performed from command-line, see <a href="#command_line">Command-line options</a> how.
		</p>

		<a name="#command_line"></a>
		<h4>Command-line options</h4>
		<p class="stdtext">
			Behaviour of Configuration Editor can be influenced by set of command-line arguments.
			<br>Syntax: <b>Oatc.OpenMI.ConfigurationEditor.exe [-opr OPRFILE | -omi OMIFILE | -reg | -unreg | -help] [-mta]</b>
			<table class="commandline_table" cellspacing="5">
				<tr>
					<td><b>-opr OPRFILE</b></td>
					<td>Opens Configuration Editor project from specific OPRFILE.</td>
				</tr>
				<tr>
					<td><b>-omi OMIFILE</b></td>
					<td>Creates a new composition and adds model from OMIFILE into it.</td>
				</tr>
				<tr>
					<td><b>-reg</b></td>
					<td>Registers OPR and OMI file extensions in Windows registry to be opened with
						this Configuration Editor executable.</td>
				</tr>
				<tr>
					<td><b>-unreg</b></td>
					<td>Discards all OPR and OMI file extension registrations from Windows registry.</td>
				</tr>
				<tr>
					<td><b>-help</b></td>
					<td>Shows window with description of command-line options.</td>
				</tr>
				<tr>
					<td><b>-mta</b></td>
					<td>Application creates and enters a multi-threaded apartment COM model at startup.</td>
				</tr>
			</table>
			Note: <b>-mta</b> option is useful if you are using models wrapping COM objects,
			because some of them may require this setting to work properly. By default, single-thread apartment (STA) is used.
		</p>
		<h4>Command-line execution (Oatc.OpenMI.ComandLine.exe)</h4>
		<p class="stdtext">
			This utility is used to run OpenMI compositions from the
			command-line. If the user installed the Configuration Editor using the msi installer, then this utility can be found in the same place under "Program Files".
			Otherwise, it can be downloaded and built from sourceforge.
			<br>Syntax: <b>Oatc.OpenMI.ComandLine.exe -r OPR_FILE [-v] [-mta]</b>
			<table class="commandline_table" cellspacing="5" ID="Table1">
				<tr>
					<td><b>-r OPR_FILE</b></td>
					<td>Runs simulation of specified Configuration Editor project.</td>
				</tr>
				<tr>
					<td><b>-v</b></td>
					<td>Verbose mode off.</td>
				</tr>
				<tr>
					<td><b>-mta</b></td>
					<td>Application creates and enters a multi-threaded apartment COM model at startup.</td>
				</tr>
				<tr>
					<td><b>-help</b></td>
					<td>Shows help.</td>
				</tr>
			</table>
			Note: <b>-mta</b> option is useful if you are using models wrapping COM objects,
			because some of them may require this setting to work properly. By default, single-thread apartment (STA) is used.


		</p>
		<h2>Licence</h2>
		<p>
Copyright (c) 2005,2006,2007, OpenMI Association<br />
All rights reserved.<br /><br />

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:<br /><br />
</p>

<u1>
<li>Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.<br /><br /></li>

<li>Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.<br /><br /></li>

<li>Neither the name of the OpenMI Association nor the names of its contributors may
be used to endorse or promote products derived from this software without specific
 prior written permission.</li>
</u1>

       <br />
        <br />
THIS SOFTWARE IS PROVIDED BY "OpenMI Association" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL "OpenMI Association" BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.<br /><br />

Contact info:<br /><br />
  URL: www.openmi.org<br /><br />
Email: sourcecode@openmi.org<br /><br />
Discussion forum available at www.sourceforge.net<br /><br />
		<h2>Links</h2>
		<ul class="stdtext">
			<li>
				<a href="http://www.openmi.org">http://www.openmi.org</a> - Official page of
				OpenMI.</li>
			<li>
				<a href="http://sourceforge.net/projects/openmi">http://sourceforge.net/projects/openmi</a>
				- Here you can obtain latest version of all public OpenMI software and
				documents, report bugs, join forums, etc...</li>
		</ul>
		<span class="endlabel">Copyright(c) OpenMI Association, last modified at 12/12/2007.</span>
	</body>
</html>
